home *** CD-ROM | disk | FTP | other *** search
/ NeXT Enterprise Objects Framework 1.1 / NeXT Enterprise Objects Framework 1.1.iso / NextDeveloper / Headers / foundation / NSCoder.h < prev    next >
Text File  |  1994-07-13  |  4KB  |  95 lines
  1. /*      NSCoder.h
  2.     Abstract class for serializing arbitrary objects
  3.     NSArchiver subclasses NSCoder
  4.     Copyright 1993, 1994, NeXT Computer Inc.
  5. */
  6.  
  7. #import <foundation/NSString.h>
  8.  
  9. /****************** Basic functionality **********************/
  10.  
  11. @interface NSCoder:NSObject
  12.  
  13. - (void)encodeValueOfObjCType:(const char *)type at:(const void *)addr;
  14.     /* Serializes ObjC data; data must be passed by reference;
  15.     Example:
  16.      [encoder encodeValueOfObjCType:@encode(typeof(item)) at:&item];
  17.     */
  18.  
  19. - (void)encodeDataObject:(NSData *)data;
  20.     /* Encodes an NSData.  Must be defined by subclasses.   */
  21.  
  22. - (void)decodeValueOfObjCType:(const char *)type at:(void *)data;
  23.     /* Deserializes ObjC data; data is filled according to type;
  24.     Contrary to normal conventions, decoded objects must be released by caller.
  25.     Example:
  26.     [decoder decodeValueOfObjCType:@encode(typeof(item)) at:&item];
  27.     Decoded CStrings (char *)s must be free'd  
  28.     */
  29.  
  30. - (NSData *)decodeDataObject;
  31.     /* Returns an autoreleased NSData.  Must be defined by subclasses.   */
  32.  
  33. - (unsigned)versionForClassName:(NSString *)className;
  34.     /* Returns the version stored in the encoding;
  35.     May raise if class not encountered */
  36.  
  37. @end
  38.  
  39. /****************** Extended functionality **********************/
  40.  
  41. /* generic implementations are provided so that one can implement
  42.    coding methods without needing to know the class of the coder */
  43.  
  44. @interface NSCoder (NSExtendedCoder)
  45.     
  46. - (void)encodeObject:object;
  47.     /* Shortcut for [self encodeValuesOfObjCTypes:@encode(typeof(object)) at:&object];
  48.     object may be nil;
  49.     Note however that some subclasses may have a more efficient encoding when using -encodeObject: and therefore that decoding must be done with -decodeObject  */
  50.  
  51. - (void)encodePropertyList:plist;
  52.     /* Encodes the plist serialized as an NSData.
  53.     Note however that some subclasses may have a more efficient encoding when using -encodePropertyList: and therefore that decoding must be done with -decodePropertyList;
  54.     PList are constrained to be (and to contain) objects that are one of: NSDictionary, NSArray, NSString, NSData;
  55.     Mutability and class are lost upon decoding; Other restrictions apply: no cycles, dags transformed to trees.
  56.     */
  57.  
  58. - (void)encodeRootObject:rootObject;
  59.     /* calls encodeObject: */
  60.  
  61. - (void)encodeBycopyObject:anObject;
  62.     /* calls encodeObject: */
  63.  
  64. - (void)encodeConditionalObject:object;
  65.     /* calls encodeObject: */
  66.  
  67. - (void)encodeValuesOfObjCTypes:(const char *)types, ...;
  68.     /* Last arguments specify addresses of values to be written.  It might seem surprising to specify values by address, but this is extremely convenient for copy-paste with -decodeValuesOfObjCTypes calls.  A more down-to-the-earth cause for this passing of addresses is that values of arbitrary size is not well supported in ANSI C for functions with variable number of arguments. */
  69.  
  70. - (void)encodeArrayOfObjCType:(const char *)type count:(unsigned)count at:(const void *)array;
  71.  
  72. - decodeObject;
  73.     /* object is autoreleased */
  74.  
  75. - decodePropertyList;
  76.   /* Returns an autoreleased plist: must retain if stored, as usual;
  77.   Note that in -decodeValueOfObjCType:at: objects set are owned by caller*/
  78.  
  79. - (void)decodeValuesOfObjCTypes:(const char *)types, ...;
  80.     /* Last arguments specify addresses of values to be read. */
  81.     /* objects are NOT autoreleased: caller must release */
  82.  
  83. - (void)decodeArrayOfObjCType:(const char *)itemType count:(unsigned)count at:(void *)array;
  84.  
  85. - (void)setObjectZone:(NSZone *)zone;
  86.     /* zone may be NULL.  NSCoder's implementation ignores this.  Other coders might want to provide this functionality. */
  87.  
  88. - (NSZone *)objectZone;
  89.     /* NSCoder's implementation just returns NSDefaultMallocZone(), but coders which honor setObjectZone: will want to override. */
  90.  
  91. - (unsigned)systemVersion;
  92.     /* NSCoder's implementation just returns 1000, but coder's which care should override. */
  93.  
  94. @end
  95.